feat(cli): objectstack dev --cert/--key terminates TLS in the dev process, and the canonical origin follows the listener - #17725

…d the argument rather than the argument list

`serve-port-readback.e2e.test.ts` runs only in the nightly `e2e` tier, so no
pull request can redden it. Two source-text pins in its ANTI-VACUITY describe
read the raw file, and both went red on `main` for reasons that were never
about the product:

  - the print-order pin did `indexOf` over the whole of `src/utils/format.ts`.
    #17892 added a docblock quoting `Press Ctrl+C to stop` 281 lines above the
    `console.error` that prints it, so the raw read put the tail at offset
    38075 and the `API:` row at 47343 and the assertion reported a print order
    that had never changed. In code position the two are 47343 and 53551, i.e.
    line 984 before line 1081, exactly as the pin claims.
  - the banner pin held the byte-exact `resolveAuthBaseUrl(boundPort)` call.
    #17725 added a `boundProtocol` argument. The per-PR sibling
    `src/commands/serve-bound-port-publication.test.ts` was updated in that
    same commit; this nightly-only copy could not be, and had no way to say so
    until the next sweep.

Both pins now read through `scripts/js-comment-mask.mjs`, the tree's one
answer to code-versus-prose, which also closes the other direction: a comment
naming a pinned spelling can no longer satisfy the pin with no code behind it.
The mask carries its own anti-vacuity control (blanked in place, and blanked
something).

The banner pin now binds the ARGUMENT — the row is derived from `boundPort` —
and tolerates whatever else the call grows, which is the division of labour
the two tiers imply: the per-PR sibling keeps the byte-exact line and reddens
on the PR that moves it. That this is narrower rather than looser is proven in
the test on synthetic text: the matcher rejects `resolveAuthBaseUrl(port)` and
`resolveAuthBaseUrl(requestedPort, boundProtocol)`, and a standing negative
asserts neither requested-port spelling is in `serve.ts`.

⛔ No test renamed, skipped or deleted, and no assertion dropped: the describe
gains four assertions and loses none.

Claude-Session: https://claude.ai/code/session_01DvvamiacK328idtBYJBxV3
Co-authored-by: Claude <noreply@anthropic.com>

…n OAuth client (objectstack-ai#17210) (objectstack-ai#17755)

Fixes objectstack-ai#17210

Implements the director seat's ruling on this card
(`#issuecomment-5634036848`), option **B**: **the SDK gains no method;
the ledger row is untouched.** The one measured trap is made visible in
prose where its reader meets it. No SDK method is added, no request or
response type moves, no accept set moves, and
`packages/plugins/plugin-auth/src/auth-route-ledger.ts` is not in this
diff.

## Premises — falsified first, on `origin/main` at `396eae33`

All four rows of the dispatch's premise table hold, plus the
falsification trigger it named.

| # | premise | reading |
|:--|:--|:--|
| 1 | `oauth.applications.register` still exists | `applications: {` at
`:3997`; `register: async (req: {` at `:4043`; pin named at `:4041` |
| 2 | the request type is the vendor shape | `client_name?: string` at
`:4044` and `redirect_uris: string[]` at `:4045` in the request type;
the same two members at `:947` / `:960` in `OAuthApplication` |
| 3 | the ledger row is unchanged and still `server-only` |
`auth-route-ledger.ts:241`, `disposition: 'server-only'`, note verbatim
as quoted on the card |
| 4 | control | `disposition` returns **70** in that ledger — the probe
is live |
| 5 | PR objectstack-ai#17209's removal held: no bare `name` in the typed request |
**zero** hits for `^\s*name\??:` in lines `4043-4055`. Positive control,
**same file, same regex**: 14 bare `name` members elsewhere (`:1062`,
`:1218`, `:1267`, `:1305`, `:1741`, …) |

Every `client_name` hit in `packages/client/src/index.ts` was read in
context, not counted: `:947` (an `OAuthApplication` member), `:1008`
(inside the `OAuthApplicationPublic` `Pick`), `:4025` / `:4027` (the
existing objectstack-ai#15447 docblock), `:4044` (the request type). Premise not
falsified — `premise_still_valid: true`.

## 1. The JSDoc — landed bytes

Added to the `oauth.applications.register` docblock, after the
`metadata` paragraph and before the `Pinned by` line:

```
 * ## ⚠️ A plain `name` IS honoured somewhere — not here (objectstack-ai#17210)
 *
 * There is exactly one door that reads a body member spelled `name`, and
 * this method does not build it:
 * `POST /api/v1/auth/sys-oauth-application/register`, the ObjectStack
 * mount behind the Console's *Setup → OAuth Applications* create form.
 * The same objectstack-ai#15447 round drove both doors on one real socket: that mount
 * answered **200** to a body spelled `name`, mapped it onto
 * `client_name`, and the `sys_oauth_application` row's `name` column was
 * set; this method's route, `/oauth2/create-client`, answered **201**
 * with the value **stripped** — absent from the response, absent from
 * `applications.get`, absent from `applications.list`, and `null` in
 * that same column.
 *
 * ⛔ That mount is **not** an SDK door, and it is not withheld by
 * oversight: it is `disposition: 'server-only'` in the auth route ledger
 * (`packages/plugins/plugin-auth/src/auth-route-ledger.ts`), a
 * session-required self-service wrapper written to serve the Console's
 * form — and objectstack-ai#17210 ruled that it **stays** `server-only`, so no SDK
 * method builds its URL. To name a client from here, post `client_name`.
 *
 * The wrapper's other Console-shaped convenience is the same asymmetry's
 * second half: it splits that form's newline-separated redirect-URL
 * **textarea** into the array the vendor schema requires. ⛔ This route
 * performs no such split — `redirect_uris` must arrive **pre-split**,
 * one entry per URL, which is what an SDK caller holds anyway.
```

Both halves the ruling asked for are stated: `name` is honoured only by
the Console's server-only mount, and this route requires `redirect_uris`
pre-split.

## 2. `content/docs/protocol/objectui/actions.mdx` — the same fact, that
page's own idiom

Not a copy-paste of the JSDoc. The page is an action-authoring
reference, so the note is written to an action author, about the
`target` of the `create_oauth_application` example, and it is addressed
at the `:424` neighbourhood — a new `#### ⚠️ That target is not
interchangeable with the SDK's registration door` immediately after that
example's `resultDialog` explanation, inside the same **Result Dialog**
section. It says why the YAML above is that short (the mount does the
plain-`name` mapping and the textarea split on the action's behalf),
that the ledger carries it `server-only` for exactly that reason, and
what an author would have to change — rename the name param to
`client_name`, pre-split the redirect URLs — if they re-pointed `target`
at the provider route.

The docs-drift tool cannot surface this page for this diff (it states
the rule by its YAML inputs, so it shares no identifier with the SDK
file), which is why it was edited by hand.

## 3. The measured evidence, restated and not overstated

From the objectstack-ai#15447 round, on a real socket, driven through the real client:

- `POST /api/v1/auth/sys-oauth-application/register` with a body spelled
`name` answered **200**, the value came back as `client_name`, and the
`sys_oauth_application` row's `name` column was set.
- The same spelling posted to `/oauth2/create-client` answered **201**
with the value **stripped**: absent from the response, absent from
`oauth.applications.get`, absent from `oauth.applications.list`, `null`
in the DB column.

Nothing in this PR claims more than those two readings. In particular it
does not claim the mount is reachable from the SDK, nor that any
behaviour changed.

## 4. Changeset — `patch`, measured, not assumed

`skip-changeset` was tested and refused. `@objectstack/client`'s
`files[]` is `["dist","README.md","CHANGELOG.md"]`; after `pnpm --filter
@objectstack/client build`, the new docblock prose is present in
**both** `dist/index.d.ts` and `dist/index.d.mts` — it ships as editor
hover to every consumer.

- measurement: `grep -c "A plain \`name\` IS honoured somewhere"` → `1`
in each of the two files
- positive control, same files, same grep shape: `grep -c "the vendor's
RECORD vocabulary"` (pre-existing docblock prose) → `1` in each
- negative control: an absent marker string → `0`

Published bytes move ⇒ `patch`.
`.changeset/17210-oauth-register-name-trap-prose.md`.

## Gates

Derived mechanically with `node scripts/pm/dispatch-gates.mjs --commands
--repo objectstack-ai/objectstack` (no hand-written path list), then
reconciled with `--ran` carrying each command's own exit code, captured
before any pipe.

- **82 derived families — 81 run green, 0 UNRUN, 1 NOT MEASURED.**
- `pnpm lint` (whole repo, `eslint . --no-inline-config`) — **exit 0**.
- `pnpm --filter @objectstack/client test` — **42 files / 506 tests
passed**, including the
`oauth-applications-register-request-members.test.ts` pin.
- `pnpm --filter @objectstack/client typecheck` — **exit 0**, test layer
included (`check:test-typecheck`: 0 files / 0 errors).
- Dependency closure built first: `pnpm --filter
'@objectstack/client^...' build` — exit 0. Heavy runs went through
`scripts/pm/os-verify-lock.sh`; verdicts read from its `VERDICT
command-exit` lines.
- Control characters: `grep -naP` over both edited files, zero hits, on
top of `check:nul-bytes` green.

**NOT MEASURED: `pnpm check:dual-build-cjs-loads`, reason:** it exited
**3** with `PREREQUISITE NOT MET — this gate reads built output, and
some package has no dist/ … ⛔ This is NOT a pass: nothing was measured`.
It wants a whole-repo `pnpm build` (34 packages listed, none of them
`@objectstack/client`, which is built). That is CI's `Build Core` run,
and the gate reads emitted runtime JS where comments are stripped, so a
docblock-only diff has no way to move it. Declared rather than run.

`Clause-②: no`, re-derived from the delivered diff: three files, 33
inserted lines plus a changeset, zero deletions; no declaration, export,
accept set or published symbol moves.

## Acceptance notes

**`docs/qa/platform-checklist/areas/identity-auth.json` (`:1008`,
`:1017`, `:1078`) — read, judged out of scope, not edited.** The
dispatch left this call to me, so here is the reasoning rather than the
verdict alone.

All three lines were read in context. They belong to
`identity-auth.oauth-app-consent-loop`, and **none of them states
anything false.** `:1008` enumerates the three registration doors and
already records this mount's distinguishing behaviour (*"the
session-required wrapper that splits the redirect-URL textarea into
redirect_uris"*); `:1017` offers two of those doors as alternatives for
a step whose object is the **`client_secret`**, not the client's name;
`:1078` is a `source` row naming the ledger. Nothing there claims the
provider route honours a plain `name`. The item never names an
application, at any step, in any acceptance clause or negative — so the
trap is not reachable from it, and there is no assertion to correct.

Against that, editing it has a real cost in the checklist's own
machinery: a semantic edit owes a `revision` bump
(`scripts/check-platform-checklist.mjs` holds `revision` equal to the
last `history` entry precisely so that a changed item cannot silently
re-validate old run results), which would invalidate the item's recorded
runs for a clarification its steps never exercise.

So: read, found accurate, left alone. It is not orphaned — the carriers
that will next open it are the `checklist-author` coverage sweep and any
`checklist-test` run selecting `identity-auth.oauth-app-consent-loop`.

**Red lines held.** No `packages/spec` path in the diff.
`auth-route-ledger.ts` untouched. No `content/docs/releases/` path. No
file held by objectstack-ai#17725, objectstack-ai#17718 or objectstack-ai#17093 is reached — the diff is
`packages/client/src/index.ts`,
`content/docs/protocol/objectui/actions.mdx` and one new changeset.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01TSf4DV7ziu4V5j73e46b7c)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

… CODE, and bind the argument rather than the argument list (objectstack-ai#18519)

Part of objectstack-ai#17633

Clause-②: no

The nightly `e2e` tier was red on `main` in
`packages/cli/test/serve-port-readback.e2e.test.ts`. Reproduced first,
at the base this branch was cut from, with the tier switch the nightly
uses. Two assertions failed, and **neither was about the product** —
both source-text pins in the file's `ANTI-VACUITY` describe had decayed
while the invariants they claim still hold.

## What was red, and why

`vitest run --project integration test/serve-port-readback.e2e.test.ts`
under `OS_TEST_TIERS=nightly`, at `8cf527f8e`:

```
AssertionError: the `API:` row is no longer printed BEFORE the banner tail — keying the
read-back on the tail no longer proves the row is in the buffer: expected 47343 to be less
than 38075
AssertionError: the ready banner no longer derives its API row from `resolveAuthBaseUrl(boundPort)`
— if it now uses the REQUESTED port, the objectstack-ai#12525 read-back is vacuous by construction:
expected '// Copyright (c) 2025 ObjectStack. Li…' to contain 'externalBaseOrigin: resolveAuthBaseUr…'
 Test Files  1 failed (1)
      Tests  2 failed | 11 passed (13)
```

Both pins read the **raw** source file, and a raw read is unsound in
both directions.

**1. The print-order pin fabricated.** It ran `indexOf` over the whole
of `src/utils/format.ts`. `ed5a1e7f2` (objectstack-ai#17892) added a docblock quoting
`Press Ctrl+C to stop` at line 800 — 281 lines **above** the
`console.error` at line 1081 that prints it. So the raw read put the
tail at offset 38075 and the `API:` row at 47343, and the assertion
reported a print order that had never changed. Read in code position the
two offsets are 47343 and 53551, i.e. line 984 before line 1081, exactly
as the pin claims.

**2. The banner pin held a byte-exact call that a legitimate refactor
moved.** `89a652b83` (objectstack-ai#17725, `dev --cert/--key`) made the call
`resolveAuthBaseUrl(boundPort, boundProtocol)`. The port argument is
unchanged and still the bound one; only the argument list grew. That
commit updated the **per-PR** sibling pin,
`packages/cli/src/commands/serve-bound-port-publication.test.ts`, in the
same diff — and could not update this copy, because this file runs only
on the nightly `main` sweep and no pull request can redden it.

## The fix

Both pins now read through `scripts/js-comment-mask.mjs`, this tree's
one answer to code-versus-prose, which blanks comment spans in place so
every offset and line number survives. That repairs the fabrication and
closes the other direction at the same time: a comment naming a pinned
spelling can no longer satisfy a pin with no code behind it, which is
exactly the vacuum the describe exists to prevent. The mask carries its
own control — blanked in place (`code.length === raw.length`) and
blanked something (`code !== raw`).

The banner pin now binds the **argument** rather than the argument
**list**: the row is derived from `boundPort`, whatever else the call
grows. That is the division of labour the two tiers imply — the per-PR
sibling keeps the byte-exact line and reddens on the PR that moves it,
with that PR's author reading the failure; a nightly-only copy of the
same byte-exact claim can only go red a day later on a card nobody can
attribute.

**That this is narrower, not looser, is proven rather than asserted** —
inside the test, on synthetic text, so the proof survives any future
rewording of `serve.ts`:

```ts
expect('externalBaseOrigin: resolveAuthBaseUrl(port).baseOrigin').not.toMatch(BANNER_FROM_BOUND_PORT);
expect('externalBaseOrigin: resolveAuthBaseUrl(requestedPort, boundProtocol).baseOrigin')
  .not.toMatch(BANNER_FROM_BOUND_PORT);
```

…beside a standing negative asserting neither requested-port spelling is
in `serve.ts` at all.

⛔ No test renamed, skipped, quarantined or deleted, and no assertion
dropped. The describe gains four assertions and loses none.

## Verification

Everything below was run in a dedicated worktree at `63d19926e`, with
the dependency closure built first.

**Red, then green, same command, both with the tier env set.** The red
leg restores the base copy of the test file onto the built tree, so the
only variable is this diff:

| tree | result |
|:---|:---|
| test file at `8cf527f8e` (base) | `Tests 2 failed \| 11 passed (13)`,
the two assertions quoted above |
| this branch | `Tests 13 passed (13)` — both real `os serve` boots
included, 17.36s |

Restore proven by blob equality
(`d00e065c02c1b76bf42b641abed34b094cddf4c1` back on disk) and an empty
`git diff HEAD` with an empty `git status --porcelain`.

**Ablation — two legs, each mutating product code on disk to prove the
repaired pin still binds.** No product code is changed by this PR; these
mutations were made, measured and reverted.

| leg | mutation | on-disk proof | pin |
|:---|:---|:---|:---|
| A | `resolveAuthBaseUrl(boundPort, boundProtocol)` becomes
`resolveAuthBaseUrl(port, boundProtocol)` in `serve.ts` | bound-spelling
1 to 0, requested-spelling 0 to 1; blob `803b955f` to `a2f0aef3` | RED,
naming the requested port |
| B | the `API:` row print in `format.ts` renamed so it no longer prints
`API:` | api-row-prints 1 to 0; blob `e3dda5c8` to `9ac9622f` | RED:
`printServerReady no longer prints an API: row` |

Both restored: blob equal to the `HEAD` blob, `git diff HEAD` empty,
`git status --porcelain` empty.

**Gate families.** `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` from the actual changed path, reconciled
with `--ran`: **49 derived / 49 run / 0 NOT-MEASURED / 0 UNRUN**.

- 47 green.
- `pnpm check:dual-build-cjs-loads` exited **3** (`PREREQUISITE NOT
MET`, packages with no `dist/`) on the first pass — recorded as neither
pass nor fail, then re-run after a full `turbo run build` and **green**:
104 published require entry points across 67 packages load, 620 emitted
CommonJS files parse.
- `pnpm check:cross-package-test-inputs` exits **1**, rooted in
`packages/cli/test/init-created-files-summary.e2e.test.ts` —
pre-existing wherever `packages/spec/dist` is built, already filed as
objectstack-ai#18353 / objectstack-ai#18348, and not a path this diff touches. It does not name this
PR's file (0 occurrences in its output).

**Beyond the derivation** (the standing blind spot — the derivation
never names the lint family):

- `pnpm lint` — repo-wide, `eslint . --no-inline-config`, **exit 0** at
`63d19926e`.
- `pnpm --filter @objectstack/cli typecheck` — exit 0, test layer
included (`tsconfig.test.json`, ledger unchanged at 3 files / 28 errors
/ 6 pinned signatures).
- `pnpm --filter @objectstack/cli exec vitest run --project unit` —
`Test Files 211 passed (211)`, `Tests 3003 passed (3003)`. That tier
carries `test/vitest-tiers-partition.test.ts`, which is what would
notice if the new import had moved this file between tiers. It did not.

## Changeset

`skip-changeset`, graded from what actually moves rather than from the
shape of the diff. `packages/cli` declares `files: ["dist", "README.md",
"CHANGELOG.md"]`; `npm pack --dry-run --json` ships **533 files, 0 of
them under `test/`** and 0 matching `serve-port-readback`. The one
changed path is not in any published tarball, so no released package
moves.

## Acceptance notes

- **This PR carries no closing keyword for objectstack-ai#17633, deliberately.** The
nightly workflow files nothing, edits nothing and closes nothing on
green, so closure is a later reading of a green nightly and not
something a merge can assert. Closing on the repair rather than on the
confirmation would throw the card away along with its `os-nightly-tiers`
marker if the next sweep is red for any other reason.
- The card's `priority:p1` and everything in its comment thread were
graded fresh and not inherited: the thread discusses older,
already-repaired defects in other files, and the body — rewritten in
place by the nightly's `report` job — names only this file.
- Observation, not filed: the two source pins repaired here are
near-duplicates of pins in
`packages/cli/src/commands/serve-bound-port-publication.test.ts`, which
runs per-PR. A byte-exact source pin that lives **only** in a
nightly-only tier cannot be kept honest by the PR that moves the source
— that is the mechanism behind this red, and this file is unlikely to be
the only place it holds. Whether such pins belong in the nightly tier at
all is a wider question than this card.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01DvvamiacK328idtBYJBxV3)_

Co-authored-by: Claude <noreply@anthropic.com>